home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / gethostbyname.z / gethostbyname
Encoding:
Text File  |  2002-10-03  |  14.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))                                            ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r,
  10.      gethostent, gethostent_r, fgethostent, fgethostent_r, sethostent,
  11.      endhostent, herror, hstrerror - get network host entry
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttyyyyppppeeeessss....hhhh>>>>
  15.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ssssoooocccckkkkeeeetttt....hhhh>>>>
  16.      ####iiiinnnncccclllluuuuddddeeee <<<<nnnneeeettttiiiinnnneeeetttt////iiiinnnn....hhhh>>>>
  17.      ####iiiinnnncccclllluuuuddddeeee <<<<nnnneeeettttddddbbbb....hhhh>>>>
  18.  
  19.      eeeexxxxtttteeeerrrrnnnn iiiinnnntttt hhhh____eeeerrrrrrrrnnnnoooo;;;;
  20.  
  21.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee))));;;;
  22.  
  23.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee____rrrr((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****hhhheeeennnntttt,,,, cccchhhhaaaarrrr ****bbbbuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffssssiiiizzzzeeee,,,, iiiinnnntttt ****hhhh____eeeerrrrrrrrnnnnoooopppp))));;;;
  24.  
  25.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ggggeeeetttthhhhoooossssttttbbbbyyyyaaaaddddddddrrrr((((ccccoooonnnnsssstttt vvvvooooiiiidddd ****aaaaddddddddrrrr,,,, ssssoooocccckkkklllleeeennnn____tttt aaaaddddddddrrrrlllleeeennnn,,,, iiiinnnntttt ttttyyyyppppeeee))));;;;
  26.  
  27.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ggggeeeetttthhhhoooossssttttbbbbyyyyaaaaddddddddrrrr____rrrr((((ccccoooonnnnsssstttt vvvvooooiiiidddd ****aaaaddddddddrrrr,,,, ssssiiiizzzzeeee____tttt aaaaddddddddrrrrlllleeeennnn,,,, iiiinnnntttt ttttyyyyppppeeee,,,, ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****hhhheeeennnntttt,,,, cccchhhhaaaarrrr ****bbbbuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffssssiiiizzzzeeee,,,, iiiinnnntttt ****hhhh____eeeerrrrrrrrnnnnoooopppp))));;;;
  28.  
  29.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ggggeeeetttthhhhoooosssstttteeeennnntttt((((vvvvooooiiiidddd))));;;;
  30.  
  31.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ggggeeeetttthhhhoooosssstttteeeennnntttt____rrrr((((ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****hhhheeeennnntttt,,,, cccchhhhaaaarrrr bbbbuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffssssiiiizzzzeeee))));;;;
  32.  
  33.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ffffggggeeeetttthhhhoooosssstttteeeennnntttt((((FFFFIIIILLLLEEEE ****ffff))));;;;
  34.  
  35.      ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****ffffggggeeeetttthhhhoooosssstttteeeennnntttt____rrrr((((FFFFIIIILLLLEEEE ****ffff,,,, ssssttttrrrruuuucccctttt hhhhoooosssstttteeeennnntttt ****hhhheeeennnntttt,,,, cccchhhhaaaarrrr bbbbuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffssssiiiizzzzeeee))));;;;
  36.  
  37.      vvvvooooiiiidddd sssseeeetttthhhhoooosssstttteeeennnntttt((((iiiinnnntttt ssssttttaaaayyyyooooppppeeeennnn))));;;;
  38.  
  39.      vvvvooooiiiidddd eeeennnnddddhhhhoooosssstttteeeennnntttt((((vvvvooooiiiidddd))));;;;
  40.  
  41.      vvvvooooiiiidddd hhhheeeerrrrrrrroooorrrr((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg))));;;;
  42.  
  43.      cccchhhhaaaarrrr ****hhhhssssttttrrrreeeerrrrrrrroooorrrr((((iiiinnnntttt eeeerrrrrrrr))));;;;
  44.  
  45. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  46.      _g_e_t_h_o_s_t_b_y_n_a_m_e, _g_e_t_h_o_s_t_b_y_a_d_d_r and their reentrant counterpoints each
  47.      return a pointer to a _h_o_s_t_e_n_t data structure describing an Internet host
  48.      referenced by name or by address, respectively.  This structure contains
  49.      either the information obtained from broken-out fields from a line in
  50.      /_e_t_c/_h_o_s_t_s.  or some other back-end hosts database.
  51.  
  52.           struct    hostent {
  53.                char *h_name;       /* official name of host */
  54.                char **h_aliases;   /* alias list */
  55.                int  h_addrtype;    /* host address type */
  56.                int  h_length;      /* length of address */
  57.                char **h_addr_list; /* list of addresses from name server */
  58.           };
  59.           #define   h_addr  h_addr_list[0]   /* address, for backward
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))                                            ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))
  71.  
  72.  
  73.  
  74.                                            compatibility */
  75.  
  76.      The members of this structure are:
  77.  
  78.      h_name        Official name of the host.
  79.  
  80.      h_aliases     A zero terminated array of alternate names for the host.
  81.  
  82.      h_addrtype    The type of address being returned; currently always
  83.                    AF_INET.
  84.  
  85.      h_length      The length, in bytes, of the address.
  86.  
  87.      h_addr_list   A zero terminated array of network addresses for the host.
  88.                    Host addresses are returned in network byte order.
  89.  
  90.      h_addr        The first address in h_addr_list; this is for backward
  91.                    compatibility.
  92.  
  93.      The _n_a_m_e argument to _g_e_t_h_o_s_t_b_y_n_a_m_e is a character string containing an
  94.      Internet hostname or an Internet address in standard dot notation (see
  95.      _i_n_e_t(3N)).  If the name contains no dot, and if the environment variable
  96.      HOSTALIASES contains the name of an alias file, the alias file is first
  97.      searched for an alias matching the input name.  See _h_o_s_t_n_a_m_e(5) for the
  98.      alias file format.  The _a_d_d_r argument to _g_e_t_h_o_s_t_b_y_a_d_d_r points to a buffer
  99.      containing a 32-bit Internet host address in network byte order.  _a_d_d_r_l_e_n
  100.      contains the address length in bytes; it should be set to sizeof(struct
  101.      in_addr).  _t_y_p_e specifies the address family and should be set to
  102.      AF_INET.
  103.  
  104.      The _g_e_t_h_o_s_t_b_y_n_a_m_e and _g_e_t_h_o_s_t_b_y_a_d_d_r routines only parse /_e_t_c/_h_o_s_t_s format
  105.      configuration files.  An external data supplier nsd(1M) may be used to
  106.      provide data from another source such as the Domain Name Service daemon
  107.      named, or the NIS databases.
  108.  
  109.      An administrator may specify a default ordering of the services in the
  110.      nsd configuration file /_e_t_c/_n_s_s_w_i_t_c_h._c_o_n_f.
  111.  
  112.      When using the Domain Name Server, _g_e_t_h_o_s_t_b_y_n_a_m_e searches for the named
  113.      host in the current domain and its parents unless the name ends in a dot.
  114.      See _h_o_s_t_n_a_m_e(5) for the domain search procedure.  Also when using the
  115.      name server, _g_e_t_h_o_s_t_b_y_n_a_m_e restricts the length of each subdomain name in
  116.      a hostname to at most 63 characters.
  117.  
  118.      When nsd is running, _g_e_t_h_o_s_t_e_n_t obtains the next entry in the
  119.      _h_o_s_t_s._b_y_a_d_d_r table.  _s_e_t_h_o_s_t_e_n_t and _e_n_d_h_o_s_t_e_n_t reset the pointer into the
  120.      map to the beginning.
  121.  
  122.      If nsd is not running, _g_e_t_h_o_s_t_e_n_t reads the next line of /_e_t_c/_h_o_s_t_s,
  123.      opening the file if necessary.  _s_e_t_h_o_s_t_e_n_t opens and rewinds the file.
  124.      If the _s_t_a_y_o_p_e_n flag is non-zero, the file is not closed after each call
  125.      to _g_e_t_h_o_s_t_b_y_n_a_m_eor_g_e_t_h_o_s_t_b_y_a_d_d_r.  _e_n_d_h_o_s_t_e_n_t closes the file.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))                                            ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))
  137.  
  138.  
  139.  
  140.      The routines fgethostent and fgethostent_r will return the next line from
  141.      the supplied file broken out into a hostent structure.  This file must be
  142.      of the same format as /_e_t_c/_h_o_s_t_s .
  143.  
  144.      The routines gethostbyname, gethostbyaddr, gethostent, and fgethostent
  145.      all return pointers to data in a static space.  Reentrant versions of
  146.      each of these are supplied as gethostbyname_r, gethostbyaddr_r,
  147.      gethostent_r and fgethostent_r.  These routines parse the results into
  148.      passed in space.  They each have extra arguments for an address to a
  149.      struct hostent structure and a flat buffer.
  150.  
  151. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  152.      Error return status from _g_e_t_h_o_s_t_b_y_n_a_m_e and _g_e_t_h_o_s_t_b_y_a_d_d_r is indicated by
  153.      return of a null (0) pointer.  The global integer _h__e_r_r_n_o can then be
  154.      checked to see whether this is a temporary failure or an invalid or
  155.      unknown host.  The routine _h_e_r_r_o_r can be used to print an error message
  156.      to file descriptor 2 (standard error) describing the failure.  If its
  157.      argument _s_t_r_i_n_g is non-NULL, it is printed, followed by a colon and a
  158.      space.  The error message is printed with a trailing newline.  To
  159.      simplify variant formatting of messages, _h_s_t_r_e_r_r_o_r takes an error number
  160.      (typically _h__e_r_r_n_o) and returns the corresponding message string.
  161.  
  162.      _h__e_r_r_n_o can have the following values:
  163.  
  164.      HOST_NOT_FOUND  No such host is known.
  165.  
  166.      TRY_AGAIN       This is usually a temporary error and means that the
  167.                      local server did not receive a response from an
  168.                      authoritative server.  A retry at some later time may
  169.                      succeed.
  170.  
  171.      NO_RECOVERY     Some unexpected server failure was encountered.  This is
  172.                      a non-recoverable error.
  173.  
  174.      NO_DATA         The requested name is valid but does not have an IP
  175.                      address; this is not a temporary error.  This means that
  176.                      the name is known to the name server but there is no
  177.                      address associated with this name.  Another type of
  178.                      request to the name server using this domain name results
  179.                      in an answer; for example, a mail-forwarder can be
  180.                      registered for this domain.
  181.  
  182. NNNNOOOOTTTTEEEE
  183.      The Mips ABI specifies nothing but local files so applications which wish
  184.      to use anything else must compile with libc prior to libnsl in the
  185.      library list.
  186.  
  187.      When nsd is running changes to the local host file may not be noticed by
  188.      gethostent() until the enumeration cache file has timed out.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))                                            ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN))))
  203.  
  204.  
  205.  
  206. FFFFIIIILLLLEEEESSSS
  207.      /etc/hosts /etc/nsswitch.conf
  208.      /etc/resolv.conf     contains addresses of remote name servers
  209.  
  210. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
  211.      HOSTALIASES     contains hostname aliases
  212.      getaddrinfo(3), getnameinfo(3), getipnodebyname(3), named(1M), nsd(1N),
  213.      gethostent(3N), resolver(3N), hosts(4), resolver(4), hostname(5).
  214.  
  215.      _I_R_I_X _N_e_t_w_o_r_k _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e
  216.  
  217.      _I_R_I_X _A_d_m_i_n: _N_e_t_w_o_r_k_i_n_g _a_n_d _M_a_i_l
  218.  
  219. BBBBUUUUGGGGSSSS
  220.      Only the Internet address format is currently understood.
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.